home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / basic / pbasmlib.zip / XMS.DOC < prev   
Text File  |  1994-02-12  |  11KB  |  266 lines
  1. PBASMLIB Assembly Language Routines for PB3C
  2. Version 1.0
  3. Extended Memory (XMS) Module
  4. (C) Copyright 1994 by Tim Gerchmez
  5. All Rights Reserved.
  6.  
  7. This module interfaces you to XMS (Extended Memory) in your computer,
  8. available on the PC-AT and up.  You will be able to access any or all of
  9. these routines by including the statements $INCLUDE "PBASMLIB.INC" and
  10. $LINK "PBASMLIB.PBL" at the top of your PowerBASIC programs.  An interface
  11. to EMS (Expanded Memory) is included in a separate module.
  12.  
  13. Many of these functions let you access XMS at a very low level.  For the
  14. easiest way to access XMS, see XMSSTORESTRING and XMSRECALLSTRING.
  15.  
  16. The following error messages are returned for the
  17. XMS routines, unless otherwise indicated.  Most
  18. routines that return errors will return only a few of
  19. the error numbers indicated below.
  20.  
  21. 80h = function not implemented
  22. 81h = VDISK was detected
  23. 82h = A20 error occurred
  24. 8Eh = general driver error
  25. 8Fh = unrecoverable driver error
  26. 90h = HMA does not exist
  27. 91h = HMA is already in use
  28. 92h = DX is less than the /HMAMIN= parameter
  29. 93h = HMA is not allocated
  30. 94h = A20 line still enabled
  31. A0h = all extended memory is allocated
  32. A1h = all XMS handles are allocated
  33. A2h = invalid handle
  34. A3h = source handle is invalid
  35. A4h = source offset is invalid
  36. A5h = destination handle is invalid
  37. A6h = destination offset is invalid
  38. A7h = length is invalid
  39. A8h = move has an invalid overlap
  40. A9h = parity error occurred
  41. AAh = block is not locked
  42. ABh = block is locked
  43. ACh = block lock count overflowed
  44. ADh = lock failed
  45. B0h = only a smaller UMB is available
  46. B1h = no UMB's are available
  47. B2h = UMB segment number is invalid
  48.  
  49. ================================================================================
  50. function xmsdetect
  51.  
  52. Returns -1 if an XMS (Extended Memory) handler is
  53. installed, or 0 if not.  Doesn't actually detect the
  54. presence of extended memory though (see XMSFREE for this).
  55. This routine should be called before any of the other XMS
  56. routines to make sure a handler is available.
  57.  
  58. Example: if xmsdetect then print "XMS will be used, if present."
  59.  
  60. ================================================================================
  61. sub xmsgetver(mj%,mn%,hm%)
  62.  
  63. Gets the version of the XMS driver installed.  You should make
  64. sure the XMS driver is present with XMSDETECT first.
  65.  
  66. mj%: Returns major version number
  67. mn%: Returns minor version number
  68. hm%: Returns 1 if  HMA (High Memory Area) exists.  This is
  69.      the area between 1 meg and 1 meg + 64K that holds TSR's,
  70.      device drivers, etc. without using regular DOS memory.
  71.  
  72. Example: xmsgetver ma%,mn%,hm%
  73.  
  74. ================================================================================
  75. sub xmsgetfree(lem??,tem??,er%)
  76.  
  77. Gets the amount of free XMS, total XMS available, and
  78. an error code if an err was encountered.
  79.  
  80. lem??: Returns size of largest available XMS block in K (lem??*1024)
  81. tem??: Returns total XMS memory
  82. er%: Returns 0 if no error, or error code if error (80h,81h,A0h)
  83.  
  84. Example: xmsgetfree lem??,tem??,er%
  85.  
  86. ================================================================================
  87. function xmserror
  88.  
  89. Returns the error code from the most recent XMS operation,
  90. for those operations that don't automatically return an error code
  91. such as XMSSTORESTRING and XMSRECALLSTRING.  Future versions of
  92. PBASMLIB may remove the er% parameter from many of the XMS commands
  93. and go exclusively with this routine for checking errors (this is
  94. the approach the EMS module takes).
  95.  
  96. Example: print xmserror
  97.  
  98. ================================================================================
  99. function xmsrecallstring$(ln%,h??)
  100.  
  101. Recalls the string from XMS memory that you previously
  102. stored with XMSSTORESTRING.  You should have saved the
  103. ln% and h?? variables that XMSSTORESTRING returned to you.
  104. To recall the string you saved, just call this routine (see
  105. example below).  The handle that was used is automatically
  106. deallocated, so recalling a previously saved string frees
  107. up a handle for a new string to be saved with XMSSTORESTRING.
  108. A null string will be returned if an error is encountered, and
  109. you can check the error with XMSERROR.
  110.  
  111. ln%: Set to value for original string provided by XMSSTORESTRING.  You
  112.      can intentionally decrease the value of ln% to recall less than the full
  113.      string that was originally saved, if desired.
  114.  
  115. h??: Set to value for handle provided by XMSSTORESTRING for original string
  116.  
  117. xmsrecallstring$: Returns the original string
  118.  
  119. Example: s$ = xmsrecallstring$(ln%,h??) 'Recalls string and deallocates h?? handle.
  120.  
  121. ================================================================================
  122. sub xmsstorestring(s$,ln%,h??)
  123.  
  124. Stores a string in XMS memory, returning a handle and string
  125. length for future accesses to that string in XMS memory.  This
  126. is one of the simplest XMS routines, and does most of the work
  127. for you.  Simply use XMSDETECT first to make sure an XMS handler
  128. is available.  Only a limited number of XMS handles are available,
  129. so this routine won't work well for storing many small strings.
  130. You should consolidate smaller strings into one large string before
  131. storing to XMS memory, then parse the string out after recalling.
  132. Note: If you don't deallocate the handle passed to you in h?? by
  133. calling XMSRECALLSTRING or using XMSFREE, that handle and portion of
  134. XMS memory will remain allocated until you reboot the computer!  This
  135. also applies if the program terminates abnormally or early for some reason.
  136.  
  137. s$: Set to the string to store (0 to max $STRING length).
  138.  
  139. ln%: Returns the length of the string you passed in s$ -
  140.      save this value for XMSRECALLSTRING.
  141.  
  142. h??: Returns a handle for future accesses (see XMSRECALLSTRING),
  143.      or 0 if function was unsuccessful in some way.  Possible
  144.      problems include no XMS, or not enough XMS available, no
  145.      remaining handles, etc.  Each string will take a minimum of
  146.      1K of XMS memory, and this will be in 1K multiples - for example,
  147.      a 1025 byte string will take 2K of XMS memory.  Use XMSERROR
  148.      to see which error occurred if h??=0 upon return.
  149.  
  150. Example: xmsstorestring s$,ln%,h??
  151.          if h??=0 then print "Error encountered when storing:";xmserror
  152.         s$=""  'Deallocate the memory taken by s$ since it's in XMS now
  153.         'Save values in h?? and ln% - needed for XMSRECALLSTRING!
  154.  
  155. ================================================================================
  156. sub xmsalloc(kb??,h??,er%)
  157.  
  158. Allocates XMS memory, and returns a handle to that memory
  159. for future accesses.  This is the first step in directly
  160. accessing XMS.
  161.  
  162. kb??: Set to number of K (bytes\1024) of XMS needed
  163. h??: Returns a handle to XMS memory (if er% = 0)
  164. er%: Returns 0 if OK (memory allocated), or 80h/
  165.      81h/A0h error code (see XMSGETFREE).
  166.  
  167. Example: xmsalloc 10,h??,er%
  168.          if er%=0 then print "10K Allocated under handle ";h??
  169.  
  170. ================================================================================
  171. sub xmsfreeumb(sg??,er%)
  172.  
  173. Frees the specified upper memory block (UMB).
  174.  
  175. sg??: Set to the segment address of the UMB to release
  176. er%:  Returns 0 if OK (released), or error code (80h,B2h)
  177.  
  178. Example: xmsfreeumb(sg??,er%)
  179.  
  180. ================================================================================
  181. sub xmsallocumb(sz??,sg??,az??,er%)
  182.  
  183. Allocates an upper-memory block (UMB), which is
  184. non-EMS memory above the 640K limit.
  185.  
  186. sz??: Set to size of UMB desired in paragraphs (16-byte chunks)
  187. sg??: Returns segment of UMB if successful
  188. az??: Returns actual size of UMB allocated, or largest available if failed
  189. er%: Returns 0 if successful, or error code if failed (80h,B0h,B1h)
  190.  
  191. Example: call xmsallocumb(sz??,sg??,az??,er%)
  192.  
  193. ================================================================================
  194. sub xmsresize(kb??,h??,er%)
  195.  
  196. Resizes a previously-allocated XMS handle.
  197.  
  198. kb??: Set to new block size in K
  199. h??: Set to handle returned by XMSALLOC
  200. er%: Returns 0 if ok (block resized), or
  201.      error code 80h,81h,A0h-A2h,ABh)
  202.  
  203. Example: xmsresize kb??,h??,er%
  204.          if er%=0 then print "Resize successful."
  205.  
  206. ================================================================================
  207. sub xmshandleinfo(h??,nfh%,sz??)
  208.  
  209. Gets the size of an allocated XMS handle, and the
  210. number of free XMS handles left.
  211.  
  212. h??: Set to handle to get info for
  213. nfh%: Returns number of free handles left
  214. sz??: Returns size of XMS block allocated to h?? in K.
  215.       if sz?? returns zero, an error was encountered.
  216.  
  217. Example: call xmshandleinfo(h??,nfh%,sz??)
  218.  
  219. ================================================================================
  220. sub xmsfree(h??,er%)
  221.  
  222. Frees a block of XMS memory previously allocated with
  223. XMSALLOC.
  224.  
  225. h??: Set to handle returned by XMSALLOC routine
  226. er%: Returns 0 if ok (memory deallocated), or error
  227.      code if error (80h,81h,A2h,ABh)
  228.  
  229. Example: xmsfree h??,er%
  230.  
  231. ================================================================================
  232. function xmsrecall(h??,sg??,ofs??,nbytes???,xofs???)
  233.  
  234. Moves data from XMS memory to standard (addressable) memory.
  235. To store data, use XMSSTORE instead.
  236.  
  237. h??: Set to handle returned by XMSALLOC
  238. sg??: Set to segment of regular memory to recall to
  239. ofs??: Set to offset of regular memory to recall to
  240. nbytes???: Set to number of bytes to recall from XMS.  This should
  241.            be an even number - if not, an extra byte is recalled.
  242. xofs???: Set to offset INTO the XMS block to start recalling
  243.          from.
  244.  
  245. Example: s% = xmsrecall(h??,sg??,ofs??,1024,0) 'Recall 1K of XMS starting at offset 0
  246.          if s% then print "Recall was successful."
  247.  
  248. ================================================================================
  249. function xmsstore(h??,sg??,ofs??,nbytes???,xofs???)
  250.  
  251. Moves data from standard (addressable) memory to XMS
  252. memory.  To recall the data, use XMSRECALL.
  253.  
  254. h??: Set to handle returned by XMSALLOC
  255. sg??: Set to segment of regular memory (EX: VARSEG of array)
  256. ofs??: Set to offset of regular memory (EX: VARPTR of array)
  257. nbytes???: Set to number of bytes to move to XMS.  This should
  258.            be an even number - if not, an extra byte is stored.
  259. xofs???: Set to offset INTO the XMS block you allocated, in bytes.
  260.          This would be zero if using the entire XMS block allocated.
  261. xmsstore: Returns -1 if successful, or error code if not:
  262.  
  263. Example: s% = xmsstore(h??,sg??,ofs??,1024,0) 'Stores 1K at XMS offset 0
  264.          if s% then print "Store Successful"
  265.  
  266.